/*
 * Copyright 2013 s.randoll.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package de.digiway.rapidbreeze.client.model.download;

import de.digiway.rapidbreeze.shared.rest.download.DownloadResource;
import java.util.List;

/**
 * Interface providing access to {@linkplain DownloadResource} instances.
 * instances can be added, retrieved and so on.
 *
 * @author s.randoll
 */
public interface DownloadResourceRepository {

    /**
     * Checks if a {@linkplain DownloadResource} with the given identifier
     * exists.
     *
     * @param identifier
     * @return true if exists
     */
    public boolean hasDownload(String identifier);

    /**
     * Retrieves an {@linkplain DownloadResource} instance with the given
     * identifier.
     *
     * @param identifier
     * @return instance
     * @throws IllegalArgumentException if the {@linkplain DownloadResource}
     * with the given identifier does not exist.
     */
    public DownloadResource getDownload(String identifier);

    /**
     * Retrieves a list of all available {@linkplain DownloadResource} instances
     * existing.
     *
     * @return list. never null
     */
    public List<DownloadResource> getDownloads();

    /**
     * Checks if the repository is able to add {@linkplain DownloadResource}
     * instances for the given url.
     *
     * @param url
     * @return true if yes
     */
    public boolean canHandleUrl(String url);

    /**
     * Tries to create a new {@linkplain DownloadResource} for the given url.
     *
     * @param url
     * @return {@linkplain DownloadResource} instance if the operation was
     * successful.
     * @throws IllegalArgumentException if the url cannot be handled.
     */
    public DownloadResource addDownload(String url);

    /**
     * Tries to update the given {@linkplain DownloadResource} in the
     * repository. If the operation was succesful, the updated instance will be
     * returned. Don't use the passed object anymore!
     *
     * @param resource
     * @return
     * @throws IllegalArgumentException if the resource update cannot be
     * handled.
     * @throws IllegalStateException if the repository is not able to update the
     * {@linkplain DownloadResource} due to a repository error.
     */
    public DownloadResource updateDownload(DownloadResource resource);

    /**
     * Removes the {@linkplain DownloadResource} instance.
     *
     * @param resource
     */
    public void removeDownload(DownloadResource resource);
}
